import { Canvas, Meta } from '@storybook/blocks';
import * as ButtonStories from "./button.stories";
import * as IconButtonStories from "./icon_button.stories";

<Meta title="Buttons/Docs" />

# Buttons

Buttons trigger an action such as submitting a form or showing/hiding an interface component.

## Variants

**Primary** (`"primary"`), used to initiate the main / primary action of a view or flow. Avoid to have more than one primary buttons in the same view or flow.

<Canvas of={ButtonStories.Primary} />

**Secondary** (`"secondary"`), the default and most common buttons in the interface. Use them for non primary actions.

<Canvas of={ButtonStories.Secondary} />

**Ghosts** (`"ghost"`), used for less prominent, and sometimes independent, actions (examples: add pages, add properties, etc.)

<Canvas of={ButtonStories.Ghost} />

**Destructive** (`"destructive"`), used for any action that destroys any object or data. Don't use them for actions like dettach, unlink, etc.

<Canvas of={ButtonStories.Destructive} />

## Technical notes

### Icons

Both `button*` and `icon-button*` accept an `icon` prop, which must contain an [icon ID](../foundations/assets/icon.mdx).
These are available in the `app.main.ds.foundations.assets.icon` namespace.

```clj
(ns app.main.ui.foo
  (:require
   [app.main.ui.ds.foundations.assets.icon :as i]))
```

```clj
[:> button* {:icon i/effects} "Lorem ipsum"]
```

<Canvas of={ButtonStories.WithIcon} />

### Accessibility

Icon buttons require an `aria-label`. This is also shown in a tooltip on hovering the button.

```clj
[:> icon-button* {:icon i/effects :aria-label "Lorem ipsum"}]
```

<Canvas of={IconButtonStories.Default} />

## Usage guidelines (design)

### Where to use

Penpot app has a high-density interface, so use buttons thoughtfully to establish
a clear and logical visual hierarchy, and avoid overwhelming the user.

### When to use

Buttons can be used in forms, navigation links or anywhere that needs simple,
standard button functionality. Used also to grab users' attention (i.e. navigate
to main user flows like register, etc.)
